Scattering Models & Other Glitches
==================

This page contains documentation outlining the addition of more glitch models in the workflow. The module, 'scatter.py', works through the example of adding scattered light to the workflow using the model outlined in Udall et al. 2022 (arXiv:2211.15867). This module provides functions to generate different types populations of scattered light, including slow and fast scattering, as well as methods to generate random parameters for these glitches.

General Tools
----------------------

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.inject_glitch(ts, glitch, time)</strong>
   </div>

Injects glitches into existing time series. Any type of glitch sampled at 8192 Hz can be injected using this function. It is suggested that when additional glitch models are added, developers inject them into pre-existing time series using this method.

**Parameters:**

- **ts** (gwpy.timeseries.TimeSeries) - Time series to inject glitch into
- **glitch** (np.array) - Time series of glitch, sampled at 8192 Hz
- **time** (float) - Central time of glitch injection

**Returns:**

- **gwpy.timeseries.TimeSeries** - Time series with injected glitch signal

Light Scattering
----------------------

Here, scattered light is used as an example of how to add parametrized glitch models to the workflow. We start by adding the parametrized models then build a population of parameters to sample from when generating the glitches.

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.slow_scattering(duration, n_harmonics, harmonic_frequency_delta, base_harmonic_frequency, modulation_frequency, phi, amplitude, **kwargs)</strong>
   </div>

Generates the time series of slow scattering glitch sampled at 8192 Hz.

**Parameters:**

- **duration** (float) - Duration of glitch
- **n_harmonics** (int) - Number of arches; bounded from [1,9]
- **harmonic_frequency_delta** (float) - Frequency spacing between arches
- **base_harmonic_frequency** (float) - Peak frequency of first arch
- **modulation_frequency** (float) - The modulation frequency of the scattering arches
- **phi** (list) - List of phases for each arch
- **amplitude** (list) - List of amplitudes for each arch

**Returns:**

- **np.array** - Time series containing slow scattering glitch

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.fast_scattering(duration, amplitude, microseism_coefficient, microseism_frequency, anthropogenic_coefficient, anthropogenic_frequency, phi_1, phi_2, **kwargs)</strong>
   </div>

Generates time series of fast scattering glitch sampled at 8192 Hz.

**Parameters:**

- **duration** (float) - Duration of glitch
- **amplitude** (float) - Envelope amplitude of fast scattering glitch
- **microseism_coefficient** (float) - Ratio of microseism amplitude to frequency
- **microseism_frequency** (float) - Frequency of microseism
- **anthropogenic_coefficient** (float) - Ratio of anthropogenic amplitude to frequency
- **anthropogenic_frequency** (float) - Frequency of noise caused from anthropogenic noise
- **phi_1** (float) - Phase of microseism noise
- **phi_2** (float) - Phase of anthropogenic noise

**Returns:**

- **np.array** - Time series containing fast scattering glitch

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.fast_params(seed=None, RC=False)</strong>
   </div>

Generates random parameters for fast scattering glitches. The RC argument refers to the populations of glitches seen after RC tracking was introduced in the LIGO detectors. For more information, see Soni et al. 2020 (arXiv:2007.14876).

**Parameters:**

- **seed** (NoneType or int) - Optional, random seed
- **RC** (bool) - Argument to enable sampling from a population after RC-tracking was introduced

**Returns:**

- **list** - List containing parameters of a fast scattering glitch

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.slow_params(seed=None, RC=False)</strong>
   </div>

Generates random parameters for slow scattering glitches. The RC argument refers to the populations of glitches seen after RC tracking was introduced in the LIGO detectors. For more information, see Soni et al. 2020 (arXiv:2007.14876).

**Parameters:**

- **seed** (NoneType or int) - Optional, random seed
- **RC** (bool) - Argument to enable sampling from a population after RC-tracking was introduced

**Returns:**

- **list** - List containing parameters of a slow scattering glitch 

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.rand_fast(seed=None, RC=False)</strong>
   </div>

Generates random fast scattering glitch time series.

**Parameters:**

- **seed** (NoneType or int) - Optional, random seed
- **RC** (bool) - Argument to enable sampling from a population after RC-tracking was introduced

**Returns:**

- **np.array** - Time series containing fast scattering glitch

.. raw:: html

   <div class="function-box">
   <strong>GlitchPop.scatter.rand_slow(seed=None, RC=False)</strong>
   </div>

Generates random slow scattering glitch time series.

**Parameters:**

- **seed** (NoneType or int) - Optional, random seed
- **RC** (bool) - Argument to enable sampling from a population after RC-tracking was introduced

**Returns:**

- **np.array** - Time series containing slow scattering glitch